home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / JFC.bin / TreeModelEvent.java < prev    next >
Text File  |  1998-06-30  |  10KB  |  262 lines
  1. /*
  2.  * @(#)TreeModelEvent.java    1.15 98/04/14
  3.  * 
  4.  * Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  */
  20.  
  21. package com.sun.java.swing.event;
  22.  
  23. import java.util.EventObject;
  24. import com.sun.java.swing.tree.TreePath;
  25.  
  26.  
  27. /**
  28.  * Encapsulates information describing changes to a tree model, and
  29.  * used to notify tree model listeners of the change.
  30.  * <p>
  31.  * Warning: serialized objects of this class will not be compatible with
  32.  * future swing releases.  The current serialization support is appropriate
  33.  * for short term storage or RMI between Swing1.0 applications.  It will
  34.  * not be possible to load serialized Swing1.0 objects with future releases
  35.  * of Swing.  The JDK1.2 release of Swing will be the compatibility
  36.  * baseline for the serialized form of Swing objects.
  37.  *
  38.  * @version 1.15 04/14/98
  39.  * @author Rob Davis
  40.  * @author Ray Ryan
  41.  * @author Scott Violet
  42.  */
  43. public class TreeModelEvent extends EventObject {
  44.     /** Path to the parent of the nodes that have changed. */
  45.     protected TreePath    path;
  46.     /** Indices identifying the position of where the children were. */
  47.     protected int[]    childIndices;
  48.     /** Children that have been removed. */
  49.     protected Object[]  children;
  50.  
  51.     /**
  52.      * Used to create an event when nodes have been changed, inserted, or
  53.      * removed; identifying the path to the parent of the modified items as
  54.      * an array of Objects.
  55.      * All of the modified objects are siblings which are direct descendents
  56.      * (not grandchildren) of the specified parent.
  57.      * ----TO BE VERIFIED---(eta)
  58.      * ---TO BE DETERMINED: INDICES SPECIFIED AS "1,3,5" for a 5-child list
  59.      *    or as "1,2,3" ??
  60.      *
  61.      * @param source the Object responsible for generating the event (typically
  62.      *               the creator of the event object passes <code>this</code>
  63.      *               for its value)
  64.      * @param path   an array of Object identifying the path to the
  65.      *               parent of the removed item(s), where the first element
  66.      *               of the array is the Object stored at the root node and
  67.      *               the last element is the Object stored at the parent node
  68.      * @param childIndices an array of <code>int</code> that specifies the 
  69.      *               index values of the removed items
  70.      * @param children an array of Object the orphaned child objects 
  71.      */
  72.     public TreeModelEvent(Object source, Object[] path, int[] childIndices,
  73.               Object[] children)
  74.     {
  75.     this(source, new TreePath(path), childIndices, children);
  76.     }
  77.  
  78.     /**
  79.      * Used to create an event when nodes have been removed, identifying
  80.      * the path to the parent of the removed items as a TreePath object.
  81.      * All of the removed objects must have been direct descendents (not
  82.      * grandchildren) of the specified parent.
  83.      * ----TO BE VERIFIED---(eta)
  84.      *
  85.      * @param source the Object responsible for generating the event (typically
  86.      *               the creator of the event object passes <code>this</code>
  87.      *               for its value)
  88.      * @param path   a TreePath object that identifies the path to the
  89.      *               parent of the removed item(s). In the DefaultTreeModel,
  90.      *               this object contains an array of user-data objects, 
  91.      *               but a subclass of TreePath could use some totally
  92.      *               different mechanism -- for example, a node ID number
  93.      * @param childIndices an array of <code>int</code> that specifies the 
  94.      *               index values of the removed items
  95.      * @param children an array of Object the orphaned child objects
  96.      *
  97.      * @see #TreeModelEvent(Object,Object[],int[],Object[])
  98.      * @see TreePath
  99.      */
  100.     public TreeModelEvent(Object source, TreePath path, int[] childIndices,
  101.               Object[] children)
  102.     {
  103.     super(source);
  104.     this.path = path;
  105.     this.childIndices = childIndices;
  106.     this.children = children;
  107.     }
  108.  
  109.     /**
  110.      * Used to create an event when nodes have been inserted, a node has
  111.      * changed, or the node structure has changed in some way, identifying
  112.      * the path to the change as an array of Objects.
  113.      * ----TO BE VERIFIED---(eta)
  114.      * <p>
  115.      * When the object data at a node has changed, the path points to the
  116.      * changed item. When nodes have been inserted or the tree's structure
  117.      * has changed, the path points to the parent of the changes. A
  118.      * "structure change" might involve nodes swapping position, for
  119.      * example, or it might encapsulate multiple inserts and deletes 
  120.      * (without identifying which nodes have been removed).
  121.      *
  122.      * @param source the Object responsible for generating the event (typically
  123.      *               the creator of the event object passes <code>this</code>
  124.      *               for its value)
  125.      * @param path   an array of Object identifying the path to the
  126.      *               change, where the first element of the array is the 
  127.      *               object stored at the root node and the last element
  128.      *               is the object stored at the changed node
  129.      */
  130.     public TreeModelEvent(Object source, Object[] path)
  131.     {
  132.     this(source, new TreePath(path));
  133.     }
  134.  
  135.     /**
  136.      * Used to create an event when nodes have been inserted, a node has
  137.      * changed, or the node structure has changed in some way, identifying
  138.      * the path to the change as a TreePath object.
  139.      * ----TO BE VERIFIED---(eta)
  140.      * <p>
  141.      * When the object data at a node has changed, the path points to the
  142.      * changed item. When nodes have been inserted or the tree's structure
  143.      * has changed, the path points to the parent of the changes. A
  144.      * "structure change" might involve nodes swapping position, for
  145.      * example, or it might encapsulate multiple inserts and deletes 
  146.      * (without identifying which nodes have been removed).
  147.      *
  148.      * @param source the Object responsible for generating the event (typically
  149.      *               the creator of the event object passes <code>this</code>
  150.      *               for its value)
  151.      * @param path   a TreePath object that identifies the path to the
  152.      *               change. In the DefaultTreeModel,
  153.      *               this object contains an array of user-data objects, 
  154.      *               but a subclass of TreePath could use some totally
  155.      *               different mechanism -- for example, a node ID number
  156.      *
  157.      * @see #TreeModelEvent(Object,Object[])
  158.      * @see TreePath
  159.      */
  160.     public TreeModelEvent(Object source, TreePath path) 
  161.     {
  162.     super(source);
  163.     this.path = path;
  164.     this.childIndices = new int[0];
  165.     }
  166.  
  167.     /**
  168.      * Returns the TreePath object identifying the changed node.
  169.      * Use <code>getLastPathComponent</code> on that object to
  170.      * get the data stored at that node.
  171.      *
  172.      * @return the TreePath object identifying the changed node
  173.      * @see TreePath#getLastPathComponent
  174.      */
  175.     public TreePath getTreePath() { return path; }
  176.  
  177.     /**
  178.      * Convenience method to get the array of objects from the TreePath
  179.      * instance that this event wraps.
  180.      *
  181.      * @return an array of Objects, where the first Object is the one
  182.      *         stored at the root and the last object is the one
  183.      *         stored at the node identified by the path
  184.      */
  185.     public Object[] getPath() {
  186.     if(path != null)
  187.         return path.getPath();
  188.     return null;
  189.     }
  190.  
  191.     /**
  192.      * Returns the objects that are children of the node identified by
  193.      * <code>getPath</code> at the locations specified by <code>getChildIndices</code>.
  194.      * If this is a removal event the returned objects are no longer 
  195.      * children of the parent node.
  196.      *
  197.      * @return an array of Object containing the children specified by
  198.      *         the event
  199.      * @see #getPath
  200.      * @see #getChildIndices
  201.      */
  202.     public Object[] getChildren() {
  203.     if(children != null) {
  204.         int            cCount = children.length;
  205.         Object[]       retChildren = new Object[cCount];
  206.  
  207.         System.arraycopy(children, 0, retChildren, 0, cCount);
  208.         return retChildren;
  209.     }
  210.     return null;
  211.     }
  212.  
  213.     /**
  214.      * Returns the values of the child indexes. If this is a removal event
  215.      * the indexes point to locations in the initial list where items 
  216.      * were removed. If it is an insert, the indices point to locations
  217.      * in the final list where the items were added. For node changes,
  218.      * the indices point to the locations of the modified nodes.
  219.      *
  220.      * @return an array of <code>int</code> containing index locations for
  221.      *         the children specified by the event
  222.      */
  223.     public int[] getChildIndices() {
  224.     if(childIndices != null) {
  225.         int            cCount = childIndices.length;
  226.         int[]          retArray = new int[cCount];
  227.  
  228.         System.arraycopy(childIndices, 0, retArray, 0, cCount);
  229.         return retArray;
  230.     }
  231.     return null;
  232.     }
  233.  
  234.     /**
  235.      * Returns a string that displays and identifies this object's
  236.      * properties.
  237.      *
  238.      * @return a String representation of this object
  239.      */
  240.     public String toString() {
  241.     StringBuffer   retBuffer = new StringBuffer();
  242.  
  243.     retBuffer.append(getClass().getName() + " " +
  244.              Integer.toString(hashCode()));
  245.     if(path != null)
  246.         retBuffer.append(" path " + path);
  247.     if(childIndices != null) {
  248.         retBuffer.append(" indicices [ ");
  249.         for(int counter = 0; counter < childIndices.length; counter++)
  250.         retBuffer.append(Integer.toString(childIndices[counter])+ " ");
  251.         retBuffer.append("]");
  252.     }
  253.     if(children != null) {
  254.         retBuffer.append(" children [ ");
  255.         for(int counter = 0; counter < children.length; counter++)
  256.         retBuffer.append(children[counter] + " ");
  257.         retBuffer.append("]");
  258.     }
  259.     return retBuffer.toString();
  260.     }
  261. }
  262.